<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<title>AngelScript: Serializer</title>

<link href="tabs.css" rel="stylesheet" type="text/css"/>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
<link href="navtree.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="resize.js"></script>
<script type="text/javascript" src="navtree.js"></script>
<script type="text/javascript">
  $(document).ready(initResizable);
</script>


</head>
<body>
<div id="top"><!-- do not remove this div! -->


<div id="titlearea">
<table cellspacing="0" cellpadding="0">
 <tbody>
 <tr style="height: 56px;">
  
  
  <td style="padding-left: 0.5em;">
   <div id="projectname">AngelScript
   
   </div>
   
  </td>
  
  
  
   
  
 </tr>
 </tbody>
</table>
</div>

<!-- Generated by Doxygen 1.7.5.1 -->
</div>
<div id="side-nav" class="ui-resizable side-nav-resizable">
  <div id="nav-tree">
    <div id="nav-tree-contents">
    </div>
  </div>
  <div id="splitbar" style="-moz-user-select:none;" 
       class="ui-resizable-handle">
  </div>
</div>
<script type="text/javascript">
  initNavTree('doc_addon_serializer.html','');
</script>
<div id="doc-content">
<div class="header">
  <div class="headertitle">
<div class="title">Serializer </div>  </div>
</div>
<div class="contents">
<div class="textblock"><p><b>Path:</b> /sdk/add_on/serializer/</p>
<p>The <code>CSerializer</code> implements support for serializing the values of global variables in a module, for example in order to reload a slightly modified version of the script without reinitializing everything. It will resolve primitives and script classes automatically, including references and handles. For application registered types, the application needs to implement callback objects to show how these should be serialized.</p>
<p>The implementation currently has some limitations:</p>
<ul>
<li>It can only serialize to memory, i.e. it is not possible to save the values to a file.</li>
<li>If the variables changed type when restoring, the serializer cannot restore the value.</li>
<li>The serializer will attempt to backup all objects, but in some cases an application may not want to backup the actual object, but only a reference to it, e.g. an internal application object referenced by the script. Currently there is no way of telling the serializer to do differently in this case.</li>
<li>If the module holds references to objects from another module it will probably fail in restoring the values.</li>
</ul>
<h2><a class="anchor" id="doc_addon_serializer_1"></a>
Public C++ interface</h2>
<div class="fragment"><pre class="fragment"><span class="keyword">class </span>CSerializer
{
<span class="keyword">public</span>:
  CSerializer();
  ~CSerializer();

  <span class="comment">// Add implementation for serializing user types</span>
  <span class="keywordtype">void</span> AddUserType(CUserType *ref, <span class="keyword">const</span> std::string &amp;name);

  <span class="comment">// Store all global variables in the module</span>
  <span class="keywordtype">int</span> Store(<a class="code" href="classas_i_script_module.html" title="The interface to the script modules.">asIScriptModule</a> *mod);

  <span class="comment">// Restore all global variables after reloading script</span>
  <span class="keywordtype">int</span> Restore(<a class="code" href="classas_i_script_module.html" title="The interface to the script modules.">asIScriptModule</a> *mod);
};
</pre></div><h2><a class="anchor" id="doc_addon_serializer_2"></a>
Example usage</h2>
<div class="fragment"><pre class="fragment"><span class="keyword">struct </span>CStringType;
<span class="keyword">struct </span>CArrayType;

<span class="keywordtype">void</span> RecompileModule(<a class="code" href="classas_i_script_engine.html" title="The engine interface.">asIScriptEngine</a> *engine, <a class="code" href="classas_i_script_module.html" title="The interface to the script modules.">asIScriptModule</a> *mod)
{
  <span class="keywordtype">string</span> modName = mod-&gt;<a class="code" href="classas_i_script_module.html#a4967db3ed89836ac2f3b529c499d473d" title="Gets the name of the module.">GetName</a>();

  <span class="comment">// Tell the serializer how the user types should be serialized</span>
  <span class="comment">// by adding the implementations of the CUserType interface</span>
  CSerializer backup;
  backup.AddUserType(<span class="keyword">new</span> CStringType(), <span class="stringliteral">&quot;string&quot;</span>);
  backup.AddUserType(<span class="keyword">new</span> CArrayType(), <span class="stringliteral">&quot;array&quot;</span>);

  <span class="comment">// Backup the values of the global variables</span>
  modStore.Store(mod);
  
  <span class="comment">// Application can now recompile the module</span>
  CompileModule(modName);

  <span class="comment">// Restore the values of the global variables in the new module</span>
  mod = engine-&gt;<a class="code" href="classas_i_script_engine.html#a9f7cdc52b59034e6e55eb8a56b427aa4" title="Return an interface pointer to the module.">GetModule</a>(modName.c_str(), <a class="code" href="angelscript_8h.html#ae4cf50de5273eb8c03c6e91e6e014f0ca2feb963eb04c221e251867bc3a93d79d" title="Don&#39;t return any module if it is not found.">asGM_ONLY_IF_EXISTS</a>);
  backup.Restore(mod);
}

<span class="comment">// This serializes the std::string type</span>
<span class="keyword">struct </span>CStringType : <span class="keyword">public</span> CUserType
{
  <span class="keywordtype">void</span> Store(CSerializedValue *val, <span class="keywordtype">void</span> *ptr)
  {
    val-&gt;SetUserData(<span class="keyword">new</span> std::string(*(std::string*)ptr));
  }
  <span class="keywordtype">void</span> Restore(CSerializedValue *val, <span class="keywordtype">void</span> *ptr)
  {
    std::string *buffer = (std::string*)val-&gt;GetUserData();
    *(std::string*)ptr = *buffer;
  }
  <span class="keywordtype">void</span> CleanupUserData(CSerializedValue *val)
  {
    std::string *buffer = (std::string*)val-&gt;GetUserData();
    <span class="keyword">delete</span> buffer;
  }
};

<span class="comment">// This serializes the CScriptArray type</span>
<span class="keyword">struct </span>CArrayType : <span class="keyword">public</span> CUserType
{
  <span class="keywordtype">void</span> Store(CSerializedValue *val, <span class="keywordtype">void</span> *ptr)
  {
    CScriptArray *arr = (CScriptArray*)ptr;

    <span class="keywordflow">for</span>( <span class="keywordtype">unsigned</span> <span class="keywordtype">int</span> i = 0; i &lt; arr-&gt;GetSize(); i++ )
      val-&gt;m_children.push_back(<span class="keyword">new</span> CSerializedValue(val ,<span class="stringliteral">&quot;&quot;</span>, arr-&gt;At(i), arr-&gt;GetElementTypeId()));
  }
  <span class="keywordtype">void</span> Restore(CSerializedValue *val, <span class="keywordtype">void</span> *ptr)
  {
    CScriptArray *arr = (CScriptArray*)ptr;
    arr-&gt;Resize(val-&gt;m_children.size());

    <span class="keywordflow">for</span>( <span class="keywordtype">size_t</span> i = 0; i &lt; val-&gt;m_children.size(); ++i )
      val-&gt;m_children[i]-&gt;Restore(arr-&gt;At(i));
  }
};
</pre></div> </div></div>
</div>
  <div id="nav-path" class="navpath">
    <ul>

    <li class="footer">Generated on Sun Jan 29 2012 15:41:03 for AngelScript by
    <a href="http://www.doxygen.org/index.html">
    <img class="footer" src="doxygen.png" alt="doxygen"/></a> 1.7.5.1 </li>
   </ul>
 </div>


</body>
</html>
